<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <link rel="stylesheet" href="http://www.petercorke.com/RVC/common/toolboxhelp.css">
    <title>M-File Help: Camera</title>
  </head>
  <body>
  <table border="0" cellspacing="0" width="100%">
    <tr class="subheader">
      <td class="headertitle">M-File Help: Camera</td>
      <td class="subheader-left"><a href="matlab:open Camera">View code for Camera</a></td>
    </tr>
  </table>
<h1>Camera</h1><p><span class="helptopic">Camera superclass</span></p>An abstract superclass for Toolbox camera classes.

<h2>Methods</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> plot</td> <td>plot projection of world point to image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> hold</td> <td>control figure hold for image plane window</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> ishold</td> <td>test figure hold for image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> clf</td> <td>clear image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> figure</td> <td>figure holding the image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> mesh</td> <td>draw shape represented as a mesh</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> point</td> <td>draw homogeneous points on image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> line</td> <td>draw homogeneous lines on image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> plot_camera</td> <td>draw camera in world view</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> rpy</td> <td>set camera attitude</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> move</td> <td>clone Camera after motion</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> centre</td> <td>get world coordinate of camera centre</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> delete</td> <td>object destructor</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> char</td> <td>convert camera parameters to string</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> display</td> <td>display camera parameters</td></tr>
</table>
<h2>Properties (read/write)</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> npix</td> <td>image dimensions (2x1)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> pp</td> <td>principal point (2x1)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> rho</td> <td>pixel dimensions (2x1) in metres</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> T </td> <td>camera pose as homogeneous transformation</td></tr>
</table>
<h2>Properties (read only)</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> nu</td> <td>number of pixels in u-direction</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> nv</td> <td>number of pixels in v-direction</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> u0</td> <td>principal point u-coordinate</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> v0</td> <td>principal point v-coordinate</td></tr>
</table>
<h2>Notes</h2>
<ul>
  <li>Camera is a reference object.</li>
  <li>Camera objects can be used in vectors and arrays</li>
  <li>This is an abstract class and must be subclassed and a project()
method defined.</li>
  <li>The object can create a window to display the Camera image plane, this
window is protected and can only be accessed by the plot methods of
this object.</li>
</ul>
<hr>
<a name="Camera"><h1>Camera.Camera</h1></a>
<p><span class="helptopic">Create camera object</span></p>Constructor for abstact <span style="color:red>Camera</span> class, used by all subclasses.

<strong>C</strong> = <span style="color:red>Camera</span>(<strong>options</strong>) creates a default (abstract) camera with null parameters.

<h2>Options</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1">'name', N</td> <td>Name of camera</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'image', IM</td> <td>Load image IM to image plane</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'resolution', N</td> <td>Image plane resolution: NxN or N=[W H]</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'sensor', S</td> <td>Image sensor size in metres (2x1) [metres]</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'centre', P</td> <td>Principal point (2x1)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'pixel', S</td> <td>Pixel size: SxS or S=[W H]</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'noise', SIGMA</td> <td>Standard deviation of additive Gaussian noise added to
returned image projections</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'pose', T</td> <td>Pose of the camera as a homogeneous transformation</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'color', C</td> <td>Color of image plane background (default [1 1 0.8])</td></tr>
</table>
<h2>Notes</h2>
<ul>
  <li>Normally the class plots points and lines into a set of axes that represent
the image plane.  The 'image' option paints the specified image onto the
image plane and allows points and lines to be overlaid.</li>
</ul>
<h2>See also</h2>
<p>
<a href="matlab:doc CentralCamera">CentralCamera</a>, <a href="matlab:doc fisheyecamera">fisheyecamera</a>, <a href="matlab:doc CatadioptricCamera">CatadioptricCamera</a>, <a href="matlab:doc SphericalCamera">SphericalCamera</a></p>
<hr>
<a name="centre"><h1>Camera.centre</h1></a>
<p><span class="helptopic">Get camera position</span></p><strong>p</strong> = C.<span style="color:red>centre</span>() is the 3-dimensional position of the camera <span style="color:red>centre</span> (3x1).

<hr>
<a name="char"><h1>Camera.char</h1></a>
<p><span class="helptopic">Convert to string</span></p><strong>s</strong> = C.<span style="color:red>char</span>() is a compact string representation of the camera parameters.

<hr>
<a name="clf"><h1>Camera.clf</h1></a>
<p><span class="helptopic">Clear the image plane</span></p>C.<span style="color:red>clf</span>() removes all graphics from the camera's image plane.

<hr>
<a name="delete"><h1>Camera.delete</h1></a>
<p><span class="helptopic">Camera object destructor</span></p>C.<span style="color:red>delete</span>() destroys all figures associated with the <span style="color:red>Camera</span> object and
removes the object.

<hr>
<a name="display"><h1>Camera.display</h1></a>
<p><span class="helptopic">Display value</span></p>C.<span style="color:red>display</span>() displays a compact human-readable representation of the camera
parameters.

<h2>Notes</h2>
<ul>
  <li>This method is invoked implicitly at the command line when the result
of an expression is a Camera object and the command has no trailing
semicolon.</li>
</ul>
<h2>See also</h2>
<p>
<a href="matlab:doc Camera.char">Camera.char</a></p>
<hr>
<a name="figure"><h1>Camera.figure</h1></a>
<p><span class="helptopic">Return figure handle</span></p><strong>H</strong> = C.<span style="color:red>figure</span>() is the handle of the <span style="color:red>figure</span> that contains the camera's
image plane graphics.

<hr>
<a name="hold"><h1>Camera.hold</h1></a>
<p><span class="helptopic">Control hold on image plane graphics</span></p>C.<span style="color:red>hold</span>() sets "<span style="color:red>hold</span> on" for the camera's image plane.

C.<span style="color:red>hold</span>(<strong>H</strong>) <span style="color:red>hold</span> mode is set on if <strong>H</strong> is true (or &amp;gt; 0), and off if
<strong>H</strong> is false (or 0).

<hr>
<a name="ishold"><h1>Camera.ishold</h1></a>
<p><span class="helptopic">Return image plane hold status</span></p><strong>H</strong> = C.<span style="color:red>ishold</span>() returns true (1) if the camera's image plane is in hold mode,
otherwise false (0).

<hr>
<a name="line"><h1>Camera.line</h1></a>
<p><span class="helptopic">Plot homogeneous lines on image plane</span></p>C.<span style="color:red>line</span>(<strong>L</strong>) plots lines on the camera image plane which are defined by columns
of <strong>L</strong> (3xN) considered as lines in homogeneous form: a.u + b.v + c = 0.

<hr>
<a name="mesh"><h1>Camera.mesh</h1></a>
<p><span class="helptopic">Plot mesh object on image plane</span></p>C.<span style="color:red>mesh</span>(<strong>x</strong>, <strong>y</strong>, <strong>z</strong>, <strong>options</strong>) projects a 3D shape defined by the matrices <strong>x</strong>, <strong>y</strong>, <strong>z</strong>
to the image plane and plots them.  The matrices <strong>x</strong>, <strong>y</strong>, <strong>z</strong> are of the same size
and the corresponding elements of the matrices define 3D points.

<h2>Options</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1">'Tobj', T</td> <td>Transform all points by the homogeneous transformation T before
projecting them to the camera image plane.</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'Tcam', T</td> <td>Set the camera pose to the homogeneous transformation T before
projecting points to the camera image plane.  Temporarily overrides
the current camera pose C.T.</td></tr>
</table>
Additional arguments are passed to plot as line style parameters.

<h2>See also</h2>
<p>
<a href="matlab:doc mesh">mesh</a>, <a href="matlab:doc cylinder">cylinder</a>, <a href="matlab:doc sphere">sphere</a>, <a href="matlab:doc mkcube">mkcube</a>, <a href="matlab:doc Camera.plot">Camera.plot</a>, <a href="matlab:doc Camera.hold">Camera.hold</a>, <a href="matlab:doc Camera.clf">Camera.clf</a></p>
<hr>
<a name="move"><h1>Camera.move</h1></a>
<p><span class="helptopic">Instantiate displaced camera</span></p><strong>C2</strong> = C.<span style="color:red>move</span>(<strong>T</strong>) is a new camera object that is a clone of C but its pose
is displaced by the homogeneous transformation <strong>T</strong> with respect to the
current pose of C.

<hr>
<a name="plot"><h1>Camera.plot</h1></a>
<p><span class="helptopic">Plot points on image plane</span></p>C.<span style="color:red>plot</span>(<strong>p</strong>, <strong>options</strong>) projects world points <strong>p</strong> (3xN) to the image plane and plots them.  If <strong>p</strong> is 2xN
the points are assumed to be image plane coordinates and are plotted directly.

<strong>uv</strong> = C.<span style="color:red>plot</span>(<strong>p</strong>) as above but returns the image plane coordinates <strong>uv</strong> (2xN).

If <strong>p</strong> has 3 dimensions (3xNxS) then it is considered a sequence of point sets and is
displayed as an animation.

<h2>Options</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1">'Tobj', T</td> <td>Transform all points by the homogeneous transformation T before
projecting them to the camera image plane.</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'Tcam', T</td> <td>Set the camera pose to the homogeneous transformation T before
projecting points to the camera image plane.  Overrides the current
camera pose C.T.</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'fps', N</td> <td>Number of frames per second for point sequence display</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'sequence'</td> <td>Annotate the points with their index</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'textcolor', C</td> <td>Text color for annotation (default black)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'textsize', S</td> <td>Text size for annotation (default 12)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> 'drawnow'</td> <td>Execute MATLAB drawnow function</td></tr>
</table>
Additional options are considered MATLAB linestyle parameters and are passed
directly to <span style="color:red>plot</span>.

<h2>See also</h2>
<p>
<a href="matlab:doc Camera.mesh">Camera.mesh</a>, <a href="matlab:doc Camera.hold">Camera.hold</a>, <a href="matlab:doc Camera.clf">Camera.clf</a></p>
<hr>
<a name="plot_camera"><h1>Camera.plot_camera</h1></a>
<p><span class="helptopic">Display camera icon in world view</span></p>C.<span style="color:red>plot_camera</span>(<strong>options</strong>) draw a camera as a simple 3D model in the current
figure.

<h2>Options</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1">'Tcam', T</td> <td>Camera displayed in pose T (homogeneous transformation 4x4)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1">'scale', S</td> <td>Overall scale factor (default 0.2 x maximum axis dimension)</td></tr>
</table>
<h2>Notes</h2>
<ul>
  <li>The graphic handles are stored within the Camera object.</li>
</ul>
<hr>
<a name="point"><h1>Camera.point</h1></a>
<p><span class="helptopic">Plot homogeneous points on image plane</span></p>C.<span style="color:red>point</span>(<strong>p</strong>) plots points on the camera image plane which are defined by columns
of <strong>p</strong> (3xN) considered as points in homogeneous form.

<hr>
<a name="rpy"><h1>Camera.rpy</h1></a>
<p><span class="helptopic">Set camera attitude</span></p>C.<span style="color:red>rpy</span>(<strong>R</strong>, <strong>p</strong>, <strong>y</strong>) sets the camera attitude to the specified roll-pitch-yaw angles.

C.<span style="color:red>rpy</span>(<strong>rpy</strong>) as above but <strong>rpy</strong>=[<strong>R</strong>,<strong>p</strong>,<strong>y</strong>].

<hr>

<table border="0" width="100%" cellpadding="0" cellspacing="0">
  <tr class="subheader" valign="top"><td>&nbsp;</td></tr></table>
<p class="copy">&copy; 1990-2011 Peter Corke.</p>
</body></html>